• Create ticket/issue

Follow the guide to enable codebase context checks.

Objective: Ensure all identifiers clearly express their purpose and intent, making code
self-documenting

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Objective: Ensure comprehensive error handling that provides meaningful context and graceful
degradation

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Objective: To prevent the leakage of sensitive system information through error messages while
providing sufficient detail for internal debugging.

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Objective: To ensure logs are useful for debugging and auditing without exposing sensitive
information like PII, PHI, or cardholder data.

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent
vulnerabilities

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Objective: To create a detailed and reliable record of critical system actions for security analysis
and compliance.

Status:
No mutation audit log: The newly-modified mutations update user learning/progress state (e.g., learned toggles
and count increments) without any explicit audit logging, which may violate audit trail
requirements depending on whether this data is considered critical/sensitive in your
compliance scope.

export const incrementViewCount = mutation({
  args: { wordId: v.id("words"), persian: v.string() },
  handler: async (ctx, args) => {
    const userId = await requireAuth(ctx);

    // Look up by persian text first - this is the canonical key
    const existingPersian = await ctx.db
      .query("wordProgress")
      .withIndex("by_user", (q) => q.eq("userId", userId))
      .filter((q) => q.eq(q.field("persian"), args.persian))
      .first();

    if (existingPersian) {
      // Update the existing record (shared across all instances of this word)
      await ctx.db.patch(existingPersian._id, {
        viewCount: existingPersian.viewCount + 1,
        lastSeen: Date.now(),
      });
      return existingPersian._id;
    } else {
      // No record exists for this persian word - create one


 ... (clipped 126 lines)

Learn more about managing compliance generic rules or creating your own custom rules

To improve efficiency and correctness, refactor the logic to iterate directly
over matchingWords instead of unique songIds, and use a cache to avoid
refetching song data. This ensures all word occurrences are processed.

convex/wordProgress.ts [485-515]

-// Get unique song IDs
-const songIds = [...new Set(matchingWords.map((w) => w.songId))];
+// Get song details for each song
+const songCache = new Map();
+const songsWithContext = await Promise.all(
+  matchingWords.map(async (word) => {
+    let song = songCache.get(word.songId);
+    if (!song) {
+      song = await ctx.db.get(word.songId);
+      if (!song) return null;
+      songCache.set(word.songId, song);
+    }
 
-// Get song details for each song
-const songsWithContext = await Promise.all(
-  songIds.map(async (songId) => {
-    const song = await ctx.db.get(songId);
-    if (!song) return null;
-
-    // Find the specific word instance in this song to get line number
-    const wordInSong = matchingWords.find((w) => w.songId === songId);
-    const lineNumber = wordInSong?.lineNumber ?? 0;
+    const lineNumber = word.lineNumber;
 
     // Get the line context
     const line = await ctx.db
       .query("lyrics")
       .withIndex("by_song", (q) =>
-        q.eq("songId", songId).eq("lineNumber", lineNumber),
+        q.eq("songId", word.songId).eq("lineNumber", lineNumber),
       )
       .first();
 
     return {
-      songId,
+      songId: word.songId,
       title: song.title,
       artist: song.artist,
       sourceLanguage: song.sourceLanguage,
       lineNumber,
       linePreview: line?.original?.slice(0, 50) || "",
     };
   }),
 );

[To ensure code accuracy, apply this suggestion manually]

Add a composite index by_user_persian on ["userId", "persian"] to the
wordProgress table to improve query performance.

convex/schema.ts [57-64]

 wordProgress: defineTable({
   userId: v.id("users"),
   wordId: v.id("words"),
   persian: v.string(),
   learned: v.boolean(),
   lastSeen: v.optional(v.number()),
 })
   .index("by_user", ["userId"])
+  .index("by_user_persian", ["userId", "persian"])

[To ensure code accuracy, apply this suggestion manually]